docs(agent-spec): name the v0.1.0 contradiction where readers meet it - #11

What this PR does

agent-spec.schema.yaml contradicts the canon it belongs to, and the repo has been shipping that silently. This does not fix it — the fix is #10 and it is aux-audit v0.2 — it makes the contradiction visible at the point of contact so a reader finds it from us rather than on their own.

The contradiction

schemas/trust-architecture.yaml:

Autonomy is not a slider you push to the right. It is a spectrum you choose per action, calibrated to evidence and stakes.

Enforcement lives in a mechanism, not in a prompt. […] A recommendation is not a control.

schemas/agent-spec.schema.yaml:

autonomy:
  values: ["human-in-the-loop", "human-on-the-loop", "autonomous"]
  required: true

One slider position for the whole agent, plus guarantees as free-text sentences and no field anywhere for the mechanism that enforces them.

It is not cosmetic. aux.H01 and aux.H03 take their base score from spec.autonomy; three rules read guarantees. The audit's two most prominent heuristics rest on the abstraction the standard tells readers to avoid.

Second defect: the file is not JSON Schema, though it uses the reserved $schema key as a container for a bespoke notation. Any JSON Schema tool reads it wrong.

What changes

Notices only — no behaviour, no fields, no IDs:

• header on agent-spec.schema.yaml naming both defects and pointing at [debate] agent-spec v1: per-action mandate with enforced_by, replacing the autonomy label #10
• a note on autonomy and on guarantees, at the two offending fields
• guarantees' own description now says plainly: this is a stated promise, not a verified mechanism
• one line each in packages/aux-audit/README.md, docs/audit.md and the repo tree

The CLI README already said the audit grades the spec, not the product. That caveat was too general — it papered over a specific hole, which is that the format has nowhere to declare a mechanism at all. It now says so.

Linked Issue

Interim for #10. Does not close it.

Type

• New pattern
• New gap
• Teardown
• Framework edit
• Schema fix
• Doc fix / typo / link
• Other

Comments and descriptions only. Deliberately not a schema fix — changing the format is #10, needs the debate settled first, and rewrites spec.ts.

Contribution bar — checklist

• I've read CONTRIBUTING.md.
• If this introduces or renames an ID, I opened a debate Issue first. — no IDs touched; [debate] agent-spec v1: per-action mandate with enforced_by, replacing the autonomy label #10 is open for the change that will touch them.
• If this adds a pattern, it has a diagram, a runnable example, and an anti-pattern. — n/a.
• If this adds a gap, it has a reproducible scenario and references a heuristic or trust stage. — n/a.
• CI passes (schema validation, link check). — verified locally: 34/34 tests, yamllint clean, check:schemas clean, check-coverage.py 12/12, links resolve, and the schema still parses with all nine fields intact.
• No emoji in code or schemas.
• Short sentences. Named things over adjectives.

Out of scope

The actual replacement — per-action mandate rows with a required enforced_by, human_control across five forms, and shutdown.tested. That is #10: it rewrites spec.ts, changes what aux.H01 and aux.H03 measure, and makes scores non-comparable across the boundary. Two things need settling there first: the draft's trust_stage enum uses bare T01–T04 rather than this repo's aux.T01–aux.T04, and it is worth deciding whether an input format should carry the audit's own output at all.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MhpqWEvwKp7NrmJfdXYq4M

Generated by Claude Code